home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tkman.z / tkman / man / cat1 / tkman.1
Text File  |  1994-09-22  |  28KB  |  727 lines

  1.  
  2.  
  3.  
  4. TKMAN(1)                 USER COMMANDS                14 Sep 1993
  5.  
  6.  
  7.  
  8. NAME
  9.      tkman - Tk-based manual page reader with hypertext
  10.  
  11. SYNOPSIS
  12.      A manual page browser, TkMan  offers  two  major  advantages
  13.      over  xman:  hypertext  links to other man pages (click on a
  14.      word in the text which corresponds to a man  page,  and  you
  15.      jump  there),  and  better  navigation within long man pages
  16.      with searches (both incremental and regular expression)  and
  17.      jumps  to  section headers.  TkMan also offers some conveni-
  18.      ence features, like a  user-configurable  list  of  commonly
  19.      used  man  pages,  a  one-click printout, and integration of
  20.      `whatis' and `apropos'.  Further, one may highlight,  as  if
  21.      with  a  yellow  marker,  arbitrary  passages of text in man
  22.      pages and subsequently jump directly to  these  passages  by
  23.      selecting  an  identifying  excerpt  from  a  pulldown menu.
  24.      Finally, TkMan gives one control over the  directory-to-menu
  25.      volume mapping of man pages with a capability similar to but
  26.      superior to xman's mandesc in that rather than  forcing  all
  27.      who  share  a man directory to follow a single organization,
  28.      TkMan gives control to the individual.   In  fact,  one  may
  29.      decide  he  has no use for a large set of man pages--say for
  30.      instance the programmer routines in volumes 2, 3, 4,  8--and
  31.      eliminate them from his personal database.
  32.  
  33.      Since man page formatting follows conventions but not  rigid
  34.      standards,  not all man pages can be parsed fully.  However,
  35.      most yield their section titles  and  SEE  ALSOs  and  their
  36.      emphasized  words.   TkMan  also  tries  to  filter  out the
  37.      unsightly page footers and headers put in  by  `nroff',  but
  38.      nonstandard formatting can slip by.
  39.  
  40.      This man page is slightly less current than  the  help  page
  41.      available from within TkMan.
  42.  
  43.  
  44. DESCRIPTION
  45.   Locating a man page
  46.      There are several ways  to  identify  the  manual  page  you
  47.      desire.  You can type its name into the entry box at the top
  48.      of the screen and press return or click `man'.  The name may
  49.      be  just  the  name  of the command or may include a `.n' or
  50.      `(n)' at the end where `n' specifies  in  which  section  to
  51.      look.  Man pages are matched using file name globbing (as in
  52.      `csh'), so you can use `?' to match  any  single  character,
  53.      `*'  to  match  any (zero or more) characters, `[' .. `]' to
  54.      match any single character in the enclosed class, and `{' ..
  55.      `}' to expand the enclosed strings.  If you're running TkMan
  56.      from a shell and giving it an initial man page name to  load
  57.      up  as  an  argument, use this syntax (adequately quoted for
  58.      protection from the shell), as opposed to the syntax of  the
  59.      standard   `man'   command.    Usually  TkMan  searches  the
  60.  
  61.  
  62.  
  63. UCB                                                             1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. TKMAN(1)                 USER COMMANDS                14 Sep 1993
  71.  
  72.  
  73.  
  74.      directories in your MANPATH environment variable for the man
  75.      page,  but  you  may instead provide a path name for the man
  76.      page by beginning it with `~', `/', `.' or `..'; this is the
  77.      way  to access a man page which isn't installed in a MANPATH
  78.      man directory.  Further, other Tcl interpreters may  display
  79.      a  man  page in TkMan by `send'ing a message to the function
  80.      `manShowMan' with the name of  the  desired  man  page,  for
  81.      example  `send  tkman manShowMan tcl'.  If multiple man page
  82.      names match the specification, the first match (as  searched
  83.      for  in  MANPATH order) is shown and a pulldown menu appears
  84.      which contains a list of the other matches.
  85.  
  86.      `apropos' information is available by typing  the  name  and
  87.      clicking `apropos' or hitting meta-return (for meta informa-
  88.      tion, of course).  The output of `apropos' is piped  through
  89.      `sort' and `uniq' to remove duplicates.  To pass the matches
  90.      through another filter, simply give the pipe as in a  shell,
  91.      e.g.,  `search  | grep ^g' (each space character is signifi-
  92.      cant) returns all the search-related  commands  which  begin
  93.      with  the letter `g'.  Hypertext is active within this list-
  94.      ing also.
  95.  
  96.      The `Paths' pulldown gives you complete control  over  which
  97.      directories  of  your MANPATH are searched for man pages and
  98.      apropos information.  You can call up a listing of  all  man
  99.      pages  in  a  volume through the `Volumes' pulldown menu and
  100.      then select one to view  by  double-clicking  on  its  name.
  101.      Typing  a  letter  jumps to the line in the listing starting
  102.      with that letter (capital and lower case  letters  are  dis-
  103.      tinct).   The  `all'  pseudo  volume can be useful when used
  104.      with `Paths' to obtain a complete listing of man  pages  in,
  105.      say, one directory tree.
  106.  
  107.      Once you have a man page  name  in  the  text  display  box,
  108.      whether from apropos, a volume listing or a reference within
  109.      another man page, you can double-click on it  to  hypertext-
  110.      jump to it.
  111.  
  112.      The last few  man  pages  you  looked  at  can  be  accessed
  113.      directly  through  the `History' pulldown menu.  `Shortcuts'
  114.      lists your personal favorites and is used  just  like  `His-
  115.      tory',  with  the  additional options of adding (by clicking
  116.      `+') the current man page or  removing  (`-')  it  from  the
  117.      list.
  118.  
  119.      (Man pages specified  as  above  are  processed  through  an
  120.      `nroff' filter.  TkMan can also read raw text from a file or
  121.      from a command pipeline, which can then  be  read,  searched
  122.      and  highlighted  same  as a man page.  To read from a file,
  123.      make  the  first  character  in  the  name  a  `<',  as   in
  124.      `<~/foo.txt'.   To  open  a pipe, make the first character a
  125.      `|' (vertical bar),  as  in  `|gzcat  foo.txt.gz'  or  `|cat
  126.  
  127.  
  128.  
  129. UCB                                                             2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. TKMAN(1)                 USER COMMANDS                14 Sep 1993
  137.  
  138.  
  139.  
  140.      ../foo.txt | grep bar' (that's no space after the first `|',
  141.      a space before and after any subsequent ones).  After  read-
  142.      ing  a  file, the current directory is set to its directory.
  143.      Commands are not processed by a shell, but  the  metacharac-
  144.      ters `.', `..', `~' and `$' (for environment variables), are
  145.      expanded nonetheless.  Typing is eased further by file  name
  146.      completion,  bound to the escape key.  Lone files (i.e., not
  147.      part of a pipe) are automatically uncompressed--no  need  to
  148.      read  compressed  files  through  a  `zcat' pipe.  It is not
  149.      expected that reading raw text will  be  done  much;  it  is
  150.      included so the occasional non-man page documentation may be
  151.      read from the same environment.  For more sophisticated file
  152.      browsing,  use  NBT,  my  Tcl/Tk-based  file  browser, which
  153.      available from TkMan's home FTP site, mentioned above.)
  154.  
  155.  
  156.  
  157.   Working within a man page
  158.      The `whatis' information for a man page, if any, appears  at
  159.      the top of the screen.
  160.  
  161.      To the extent it follows convention, the man page is  parsed
  162.      to  yield  its  section  and  subsection  titles  (which are
  163.      directly available from the `Sections' pulldown) and  refer-
  164.      ences  to other man pages from its SEE ALSO section (`Links'
  165.      pulldown).  One may jump directly to a section within a  man
  166.      page  or  a  man  page  referenced  in the SEE ALSO section,
  167.      respectively, by selecting the corresponding entry from  one
  168.      of  these  pulldowns.  It may be handy to tear off the `Sec-
  169.      tions' and `Links' menus (by dragging the  menu  title  with
  170.      mouse button 2 pressed).
  171.  
  172.      Within a man page or raw text file or pipe, you may added ad
  173.      hoc  highlighting, as though with a yellow marker (underlin-
  174.      ing on monochrome monitors).  Highlighted regions  may  then
  175.      be  scrolled  to  directly through the `Highlights' pulldown
  176.      menu.  To highlight a region, select  the  desired  text  by
  177.      clicking button 1, dragging to the far extent of the desired
  178.      region, releasing the button, then clicking on the `+'  next
  179.      to  `Highlights'.   To  remove  any  highlights  or portions
  180.      thereof in a region, select it as before but then  click  on
  181.      `-'.   Highlighting  information is persistent across execu-
  182.      tions of TkMan.
  183.  
  184.      You can move about the man page by using the  scrollbar,  or
  185.      typing  a  number of key combinations familiar to Emacs afi-
  186.      cionados.  Space or C-v page down and delete or M-v page up.
  187.      C-n  and  C-p  scroll up and down, respectively, by a single
  188.      line.  M-< goes to the head and M-> to the tail of the text.
  189.      One  may  "scan"  the  page by dragging up and down with the
  190.      middle mouse button pressed.  Like Emacs, C-space will  mark
  191.      one's  current location, which can be returned to later with
  192.  
  193.  
  194.  
  195. UCB                                                             3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. TKMAN(1)                 USER COMMANDS                14 Sep 1993
  203.  
  204.  
  205.  
  206.      C-x, which exchanges  the  then-current  position  with  the
  207.      saved mark; a second C-x swaps back.
  208.  
  209.      C-s initiates a search.  Subsequently typing a  few  letters
  210.      attempts  to  find  a  line  with  that string, starting its
  211.      search with the topmost line currently  visible.   A  second
  212.      C-s  finds  the  next match of the string typed so far.  (If
  213.      the current search string is empty, a second  C-s  retrieves
  214.      the  previous  search  pattern.)  C-r  is similar to C-s but
  215.      searches backwards.  Escape or C-g cancels the search.  This
  216.      incremental  search can be used to quickly locate a particu-
  217.      lar command-line option or a particular command in  a  group
  218.      (as in `csh').  At the bottom of the screen, type in a regu-
  219.      lar expression  to  search  for  and  hit  return  or  click
  220.      `Search'  to  begin  a  search.   Hit `Next' or keep hitting
  221.      return to search for the next occurance.   [`Prev'  will  be
  222.      added when Tk supports a `tag prevrange' command.]
  223.  
  224.      The tab key moves the focus from the man page  type-in  line
  225.      to the text view of the man page to the search line and back
  226.      around.
  227.  
  228.  
  229.  
  230.   Other commands
  231.      The `Occasionals' menu holds commands and options which  you
  232.      probably  won't  use  much.  The first group in this menu is
  233.      comprised of commands which you may invoke several times  in
  234.      a  single TkMan session.  `Help' returns to this information
  235.      screen.  Although virtually made obsolete by TkMan,  `Print'
  236.      makes  a copy of the current man page on dead trees, helping
  237.      to starve the planet of  life-giving  oxygen.   By  default,
  238.      incremental  searching  is  not  case sensitive, but regular
  239.      expression searching is; these settings can be toggled  with
  240.      the  next  two menu checkboxes.  If you install a new manual
  241.      pages, invoking `Rebuild Database' will permit them to  show
  242.      up  the  next time that volume list is shown and be found in
  243.      the next search without the bother  of  re-executing  TkMan.
  244.      Usually  TkMan  saves  its  persistent  variables,  only and
  245.      always, when exited with the `Quit' button.  One  may  guard
  246.      against  losing  highlighting,  shortcuts  and  other  what-
  247.      should-be  persistent  information  by   checkpointing   the
  248.      current state with the "Update operation, obviously.
  249.  
  250.      Like `xman' one  may  instantiate  multiple  viewers.   When
  251.      there  is  more  than one viewer you may choose man pages in
  252.      one viewer and have their contents shown  in  another.   Use
  253.      the  `Output'  pulldown  (which  appears  and  disappears as
  254.      relevant) to  direct  one  viewer's  output  destination  to
  255.      another.  With this feature one may easily compare two simi-
  256.      lar man pages for differences,  keep  one  man  page  always
  257.      visible,  or  examine  several  man  pages from a particular
  258.  
  259.  
  260.  
  261. UCB                                                             4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. TKMAN(1)                 USER COMMANDS                14 Sep 1993
  269.  
  270.  
  271.  
  272.      volume listing or a SEE ALSO section.  `Output' only affects
  273.      the display destination of man pages.
  274.  
  275.      You will probably only use commands in the next two clusters
  276.      of  `Occasionals'  once  or twice and leave them set for all
  277.      executions of TkMan.  Choose between  seeing  a  man  page's
  278.      `whatis'  information  and  the  full path name of the found
  279.      file with the `Show Path of Found Man' switch.  Until `wish'
  280.      has an option to startup iconified, TkMan has a checkbox for
  281.      that.  Subsection parsing doesn't work for all varieties  of
  282.      man  page macros formatting, but it can usefully augment the
  283.      Sections listing for long man pages.  At the factory,  TkMan
  284.      is  set  to  format  the  contents of man volumes on demand,
  285.      which entails a little wait the first time  that  volume  is
  286.      shown, as opposed to waiting for all volumes to be loaded at
  287.      startup but no waiting thereafter; the  `Preformat  Volumes'
  288.      switch  chooses  between  these.  If a man page has not been
  289.      formatted by `nroff', TkMan must first pipe the source  text
  290.      through   `nroff'.   By  turing  on  `Save  on  nroff',  the
  291.      `nroff'-formatted text  is  saved  to  disk  (if  possible),
  292.      thereby  eliminating  this time-consuming step the next time
  293.      the man page is read.
  294.  
  295.      `Mono' toggles between the proportionally-spaced font and  a
  296.      monospaced  one,  for  use in those man pages that rely on a
  297.      constant-width font to align columns [when Tk supports  tabs
  298.      better,  the  need  for  this  will diminish].  `Quit' exits
  299.      TkMan, of course, after saving some status information  (see
  300.      below).   To  exit without saving status information, select
  301.      the `Quit' option from the `Occasionals' pulldown.
  302.  
  303.  
  304.  
  305.  
  306. Customizing TkMan
  307.      There are three levels of configuration to TkMan.
  308.  
  309.      (1) Transparent.  Simply use TkMan and it will remember your
  310.      window size and placement and short cuts (if you quit out of
  311.      TkMan via the `Quit' button).
  312.  
  313.  
  314.      (2) Configuration file.  Most interesting persistent  infor-
  315.      mation,  like the command(s) used to print the man page, the
  316.      fonts used, and some key bindings, can be changed by editing
  317.      one's own ~/.tkman.  Thus, a single copy of TkMan (i.e., the
  318.      executable `tkman') can be shared, but each  user  can  have
  319.      his   own   customized   setup.    (The   file  ~/.tkman  is
  320.      created/rewritten every time one quits TkMan via the  `Quit'
  321.      button  in  the lower right corner.  Thus, to get a ~/.tkman
  322.      to edit, first run and quit TkMan.  Do not create  one  from
  323.      scratch  as  it  will  not  have  the proper format used for
  324.  
  325.  
  326.  
  327. UCB                                                             5
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. TKMAN(1)                 USER COMMANDS                14 Sep 1993
  335.  
  336.  
  337.  
  338.      saving other persistent information, and your work  will  be
  339.      overwritten, which is to say lost.)
  340.  
  341.      Most persistent information can be changed  in  the  obvious
  342.      way.   For example, to change the means of highlighting from
  343.      a light yellow background to an underline (to display better
  344.      on  a  monochrome  monitor),  EDIT  (change  in  place) `set
  345.      man(show,highlight)  {-background  #ffd8ffffb332}'  to  `set
  346.      man(show,highlight)  {-underline yes}' I find that dark text
  347.      is easier to read: `set man(show,fontcolor) black'
  348.  
  349.  
  350.      To change  colors  append  `option'  commands  to  ~/.tkman.
  351.      Alternatively, TkMan also works with standard X11 resources.
  352.      For instance, this is how I set my foreground and background
  353.      colors  (X11 resource lines should be placed in one's `.Xde-
  354.      faults' file, not in ~/.tkman):
  355.  
  356.      *TkMan*Foreground: SlateGray4 *TkMan*Background: beige
  357.  
  358.      Additional useful commands include `wm',  which  deals  with
  359.      the  window  manager; and `bind', which changes keyboard and
  360.      mouse bindings not related to the text display window.   For
  361.      example,  to  set  an icon image for TkMan, add this line to
  362.      the end of ~/.tkman:
  363.  
  364.      `wm iconbitmap .man @/some/directory/TkMan.xpm'
  365.  
  366.  
  367.      (3) Source code.  Of course, but if you make generally  use-
  368.      ful changes or have suggestions for some, please report them
  369.      back to me so I may share the wealth with the next release.
  370.  
  371.  
  372.  
  373.   Command line options
  374.      `-title <title>' Place `<title>' in the window's title bar.
  375.  
  376.      `-iconify' and `--iconify' Start up iconified or uniconified
  377.      (the default), respectively.
  378.  
  379.      `-iconname <name>' Use `<name>' in place of the  uniconified
  380.      window's title for the icon name.
  381.  
  382.      `-iconbitmap <bitmap-path>'  and  `-iconmask  <bitmap-path>'
  383.      Specify the icon bitmap and its mask.
  384.  
  385.      `-v' Show the current version of TkMan and exit.
  386.  
  387.      `-M <path-list>' `-M+ <path-list>' As with `man', change the
  388.      search  path  for  manual pages to the given colon-separated
  389.      list of directory subtrees.  The `-M+' option prepends these
  390.  
  391.  
  392.  
  393. UCB                                                             6
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400. TKMAN(1)                 USER COMMANDS                14 Sep 1993
  401.  
  402.  
  403.  
  404.      directories to the current list.
  405.  
  406.      There is no `-geometry'  option.   To  assign  a  persistent
  407.      geometry,  start  up  TkMan,  size  and  place the window as
  408.      desired, then (this is important) quit via the `Quit' button
  409.      in the lower right corner.
  410.  
  411.  
  412.  
  413.   Key bindings
  414.      Key bindings related to the text display box are kept in the
  415.      `sb'  array  in ~/.tkman (see the Tcl documentation for more
  416.      information on Tcl arrays).  In  editing  the  `sb(key,...)'
  417.      keyboard bindings, modifiers MUST be listed in the following
  418.      order:  `M'  (for  meta),  `C'  (control),  `A'  (alt),  `S'
  419.      (shift).  For instance, `set sb(key,MS-less) pagestart' is a
  420.      valid binding, whereas `set  sb(key,SM-less)'  is  not.   To
  421.      make a binding without a modifier key, precede the character
  422.      by `-', as in `set sb(key,-space) pagedown'.   If  you  have
  423.      NBT  and would like to share key bindings between them, save
  424.      the keybindings in their own file, then `source'  this  file
  425.      at the bottom of ~/.tkman.
  426.  
  427.  
  428.  
  429. Tkmandesc
  430.      Like `xman', TkMan gives you directory-by-directory  control
  431.      over  named volume contents.  Unlike and superior to `xman',
  432.      however, each individual controls directory-to-volume place-
  433.      ment,  rather  than  facing  a single specification for each
  434.      directory tree that must be observed by all.
  435.  
  436.      By default a matrix is created  by  taking  the  product  of
  437.      directories  in  the MANPATH crossed with volume names, with
  438.      the yield of each volume containing  all  the  corresponding
  439.      subdirectories  in  the  MANPATH.  By adding Tcl commands to
  440.      your ~/.tkman (see above), you may add new volume names  and
  441.      add,  move, copy and delete directories to/from/among direc-
  442.      tories.
  443.  
  444.      The interface to this functionality takes the  form  of  Tcl
  445.      commands,  so  you  may  need to learn Tcl--particularly the
  446.      sections on Tcl lists and, perhaps, iteration (`foreach'  or
  447.      `for')--to use this facility to its fullest.
  448.  
  449.      Directory titles and SINGLE LETTER abbrevations are kept  in
  450.      lists.  Letters MUST be unique (capital letters are distinct
  451.      from lower case), but need not correspond to  actual  direc-
  452.      tories.   In  fact,  volume letters specified here supercede
  453.      the defaults in identifying a volume in man page searches.
  454.  
  455.  
  456.  
  457.  
  458.  
  459. UCB                                                             7
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466. TKMAN(1)                 USER COMMANDS                14 Sep 1993
  467.  
  468.  
  469.  
  470.   COMMANDS
  471.      These commands are added to the file ~/.tkman (see Customiz-
  472.      ing TkMan, above).
  473.  
  474.      To set absolutely the volume names for which all directories
  475.      should be searched, EDIT the parallel arrays on these EXIST-
  476.      ING lines: `set  man(manList)  ...'  `set  man(manTitleList)
  477.      ...'
  478.  
  479.      To recreate a cross product of current section lists:  `man-
  480.      DescDefaults'
  481.  
  482.      To add "pseudo"  sections  to  default/current  volume  name
  483.      list,  at  the  end  of  the list, in alphabetical order, or
  484.      before or after  a  specific  volume:  `set  manDescAddSects
  485.      <list  of  <letter,  title  pairs>>' or `set manDescAddSects
  486.      <list of  <letter,  title  pairs>>  sort'  or  `set  manDes-
  487.      cAddSects  <list  of  <letter,  title  pairs>> before <sect-
  488.      letter>' or `set manDescAddSects  <list  of  <letter,  title
  489.      pairs>> after <sect-letter>'
  490.  
  491.      To  move/copy/delete/add  directories:  `manDescMove  <from-
  492.      list>  <to-list>  <dir-patterns>'  `manDescCopy  <from-list>
  493.      <to-list> <dir-patterns>' `manDescDelete  <from-list>  <dir-
  494.      patterns>' `manDescAdd <to-list> <dir-list>'
  495.  
  496.      The `<dir-patterns>' uses the same meta  characters  as  man
  497.      page  searching  (see above).  It is matched against MANPATH
  498.      directories  with  volume  subdirectory  appended,   as   in
  499.      `/usr/man/man3'.   `<from-list>'  and  `<to-list>'  are  Tcl
  500.      lists of the unique single letter volume names;  `*'  is  an
  501.      abbreviation for all volumes.
  502.  
  503.      Warning: Moving directories from their natural home slightly
  504.      impairs  searching speed when following a reference within a
  505.      man page.  For instance, say you've moved man  pages  for  X
  506.      Windows  subroutines  from their natural home in volume 3 to
  507.      their own volume  called  "X".   Following  a  reference  in
  508.      `XButtonEvent' to `XAnyEvent(3X11)' first searches volume 3;
  509.      not finding it, TkMan searches all volumes and finally finds
  510.      it  in volume X.  With no hint to look in volume 3 (as given
  511.      by the `3X11' suffix), the full  volume  search  would  have
  512.      begun  straight away.  (Had you double-clicked in the volume
  513.      listing  for  volume  X  or  specified  the  man   page   as
  514.      `XButtonEvent.X',  volume  X would have been searched first,
  515.      successfully.)
  516.  
  517.      To help  debug  tkmandesc  scripts,  you  may  invoke  `man-
  518.      DescShow'  to  dump  to stdout the current correspondence of
  519.      directories to volumes names.
  520.  
  521.  
  522.  
  523.  
  524.  
  525. UCB                                                             8
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532. TKMAN(1)                 USER COMMANDS                14 Sep 1993
  533.  
  534.  
  535.  
  536.   EXAMPLES
  537.      (1) To collect together all man pages in default  volumes  2
  538.      and  3  in  all directories into a volume called "Programmer
  539.      Subroutines", add these lines to the tail of ~/.tkman:
  540.  
  541.      `manDescAddSects  {{p  "Programmer   Subroutines"}}'   `man-
  542.      DescMove {2 3} p *'
  543.  
  544.      To place the new section at the same position in the  volume
  545.      pulldown list as volumes 2 and 3: `manDescAddSects {{p "Pro-
  546.      grammer Subroutines"}} after 2' `manDescMove {2 3} p *'
  547.  
  548.      To move only a selected set of directories: `manDescAddSects
  549.      {{p    "Programmer    Subroutines"}}'   `manDescMove   *   p
  550.      {/usr/man/man2 /usr/local/man/man3}'
  551.  
  552.  
  553.      (2) To have a  separate  volume  with  all  of  your  and  a
  554.      friend's  personal  man  pages,  keeping with a duplicate in
  555.      their default locations:
  556.  
  557.      `manDescAddSects  {{t  "Man  Pages  du   Tom"}   {b   "Betty
  558.      Page(s)"}}' `manDescCopy *phelps* t *' `manDescCopy *page* t
  559.      *'
  560.  
  561.  
  562.      (3) To collect the X windows man pages into two sections  of
  563.      their  own,  one  for programmer subroutines and another for
  564.      the others.
  565.  
  566.      `manDescAddSects {{x "X Windows"}} after 1' `manDescAddSects
  567.      {{X "X Subroutines"}} after 3' `manDescMove * x *X11*' `man-
  568.      DescMove x X *3'
  569.  
  570.      We must name the X Subroutines volume "X", not "x" or "xsub"
  571.      as  the  former  would duplicate the letter used for other X
  572.      man pages and the latter is a string of multiple letters.
  573.  
  574.  
  575.      (4) If you never use the  programmer  subroutines,  why  not
  576.      save time and memory by not reading them into the database?
  577.  
  578.      `manDescDelete * {*[2348]}; # braces prevent Tcl from trying
  579.      to execute [2348]'
  580.  
  581.  
  582.      Alternatively but not equivalently: `manDescDelete {2 3 4 8}
  583.      *'
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591. UCB                                                             9
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598. TKMAN(1)                 USER COMMANDS                14 Sep 1993
  599.  
  600.  
  601.  
  602.   Tkmandesc vs. xman and SGI
  603.      TkMan's `tkmandesc' capability  is  patterned  after  xman's
  604.      mandesc  files.   By placing a mandesc file at the root of a
  605.      man page directory tree, one may create pseudo  volumes  and
  606.      move  and  copy  subdirectories into them.  Silicon Graphics
  607.      has modified xman so that simply by creating a  subdirectory
  608.      in  a  regular  man  subdirectory  one creates a new volume.
  609.      This is evil.  It violates the individual user's  rights  to
  610.      arrange  the  directory-volume mapping as he pleases, as the
  611.      mandesc file or subdirectory that  spontaneously  creates  a
  612.      volume is set a single place and must be observed by all who
  613.      read  that  directory.   By  contrast,  TkMan   places   the
  614.      directory-to-volume  mapping  control in an individual's own
  615.      ~/.tkman file.  This gives the individual  complete  control
  616.      and  inflicts  no pogrom on others who share man page direc-
  617.      tories.  Therefore, mandesc files are not supported  in  any
  618.      way by TkMan.
  619.  
  620.      One may still share custom setups, however, by  sharing  the
  621.      relevant lines of ~/.tkman.  In fact, a tkmandesc version of
  622.      the standard SGI man page directory setup is included in the
  623.      `contrib'  directory  of the TkMan distribution.  For assis-
  624.      tance with SGI-specific directory manipulation, contact Paul
  625.      Raines (raines@bohr.physics.upenn.edu).
  626.  
  627.  
  628.  
  629.  
  630. AUTHOR
  631.        Tom Phelps
  632.        University of California, Berkeley
  633.        Computer Science Division
  634.        571 Evans Hall
  635.        Berkeley, CA  94720
  636.        USA
  637.  
  638.        (510) 642-8155
  639.        phelps@cs.Berkeley.EDU
  640.  
  641.  
  642.  
  643. AVAILABILITY
  644.      The latest version of TkMan is always available by anonymous
  645.      FTP at ftp.cs.Berkeley.EDU in the /ucb/mhgs directory.
  646.  
  647.  
  648.  
  649. SEE ALSO
  650.      man(1), man(7), catman(8), xman(1)
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657. UCB                                                            10
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664. TKMAN(1)                 USER COMMANDS                14 Sep 1993
  665.  
  666.  
  667.  
  668. COPYRIGHT
  669.      Copyright (c) 1993  T.A. Phelps  University  of  California,
  670.      Berkeley  Department  of Electrical Engineering and Computer
  671.      Science Computer Science Division
  672.  
  673.      PERMISSION IS GRANTED TO DISTRIBUTE  THIS  SOFTWARE  FREELY,
  674.      BUT  ONE  MAY  NOT CHARGE FOR IT OR INCLUDE IT WITH SOFTWARE
  675.      WHICH IS SOLD.
  676.  
  677.      If you send  me  bug  reports  and/or  suggestions  for  new
  678.      features,  include  the  versions  of TkMan, Tcl, Tk, X, and
  679.      UNIX, your machine and X window manager names, and a copy of
  680.      your  ~/.tkman file.  First check that values changed in the
  681.      Makefile or source code aren't being unexpectedly overridden
  682.      in ~/.tkman.
  683.  
  684.  
  685.  
  686. DISCLAIMER
  687.      Permission  to  use,  copy,  modify,  and  distribute   this
  688.      software and its documentation for educational, research and
  689.      non-profit purposes, without  fee,  and  without  a  written
  690.      agreement  is  hereby granted, provided that the above copy-
  691.      right notice and the following three  paragraphs  appear  in
  692.      all copies.
  693.  
  694.      Permission to incorporate this software into commercial pro-
  695.      ducts  may be obtained from the Office of Technology Licens-
  696.      ing, 2150 Shattuck Avenue, Suite 510, Berkeley, CA  94704.
  697.  
  698.      IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE  TO
  699.      ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CON-
  700.      SEQUENTIAL DAMAGES ARISING OUT OF THE USE OF  THIS  SOFTWARE
  701.      AND  ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA
  702.      HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  703.  
  704.      THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WAR-
  705.      RANTIES,  INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRAN-
  706.      TIES OF MERCHANTABILITY AND FITNESS FOR  A  PARTICULAR  PUR-
  707.      POSE.  THE  SOFTWARE  PROVIDED  HEREUNDER  IS  ON AN "AS IS"
  708.      BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  709.      PROVIDE  MAINTENANCE,  SUPPORT,  UPDATES,  ENHANCEMENTS,  OR
  710.      MODIFICATIONS.
  711.  
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.  
  721.  
  722.  
  723. UCB                                                            11
  724.  
  725.  
  726.  
  727.